Crate measureme

This crate provides a library for high-performance event tracing which is used by the Rust compiler’s unstable -Z self-profile feature.

The output of a tracing session will be an .mm_profdata file containing a stream of events and a string table that allows to decode the StringIds in the event stream.

Writing event trace files

The main entry point for writing event trace files is the Profiler struct.

To create a Profiler, call the Profiler::new() function and provide a Path with the directory and file name for the trace files. Alternatively, call the Profiler::with_counter() function, to choose the Counter the profiler will use for events (whereas Profiler::new() defaults to wall-time).

For more information on available counters, see the counters module documentation.

To record an event, call the Profiler::record_instant_event() method, passing a few arguments:

• event_kind: a StringId which assigns an arbitrary category to the event
• event_id: a StringId which specifies the name of the event
• thread_id: a u32 id of the thread which is recording this event

Alternatively, events can also be recorded via the Profiler::start_recording_interval_event() method. This method records a “start” event and returns a TimingGuard object that will automatically record the corresponding “end” event when it is dropped.

To create a StringId, call one of the string allocation methods:

• Profiler::alloc_string(): allocates a string and returns the StringId that refers to it

Re-exports

• pub use crate::event_id::EventId;
• pub use crate::event_id::EventIdBuilder;
• pub use crate::stringtable::SerializableString;
• pub use crate::stringtable::StringComponent;
• pub use crate::stringtable::StringId;
• pub use crate::stringtable::StringTableBuilder;

Modules

• counters
  Profiling counters and their implementation.
• event_id
• file_header
  All binary files generated by measureme have a simple file header that consists of a 4 byte file magic string and a 4 byte little-endian version number.
• rustc
  This module contains functionality specific to to the measureme integration with rustc
• stringtable
  A string table implementation with a tree-like encoding.

Structs

• Addr
  An address within a data stream. Each data stream has its own address space, i.e. the first piece of data written to the events stream will have Addr(0) and the first piece of data written to the string data stream will also have Addr(0).
• DetachedTiming
  Created by Profiler::start_recording_interval_event_detached. Must be passed to finish_recording_interval_event to record an “end” event.
• Profiler
• RawEvent
  RawEvent is how events are stored on-disk. If you change this struct, make sure that you increment file_header::CURRENT_FILE_FORMAT_VERSION.
• SerializationSink
• SerializationSinkBuilder
• TimingGuard
  When dropped, this TimingGuard will record an “end” event in the Profiler it was created by.

Enums

• PageTag

Constants

• MAX_INTERVAL_VALUE
  The max value we can represent with the 48 bits available. The highest two values are reserved for the INSTANT_MARKER and INTEGER_MARKER.
• MAX_SINGLE_VALUE
  The max value we can represent with the 48 bits available.

Functions

• split_streams
  This function reconstructs the individual data streams from their paged version.